Propagácia asynchrónneho kontextu v JavaScripte: Sledovanie požiadaviek a pokračovanie s AsyncLocalStorage

V modernom vývoji serverového JavaScriptu, najmä s Node.js, sú asynchrónne operácie všadeprítomné. Správa stavu a kontextu naprieč týmito asynchrónnymi hranicami môže byť náročná. Tento blogový príspevok skúma koncept propagácie asynchrónneho kontextu so zameraním na to, ako používať AsyncLocalStorage na efektívne sledovanie požiadaviek a pokračovanie. Preskúmame jeho výhody, obmedzenia a aplikácie v reálnom svete a poskytneme praktické príklady na ilustráciu jeho použitia.

Pochopenie propagácie asynchrónneho kontextu

Propagácia asynchrónneho kontextu sa vzťahuje na schopnosť udržiavať a šíriť kontextové informácie (napr. ID požiadaviek, údaje o autentifikácii používateľa, korelačné ID) naprieč asynchrónnymi operáciami. Bez správnej propagácie kontextu je ťažké sledovať požiadavky, korelovať záznamy a diagnostikovať problémy s výkonom v distribuovaných systémoch.

Tradičné prístupy k správe kontextu sa často spoliehajú na explicitné odovzdávanie kontextových objektov prostredníctvom volaní funkcií, čo môže viesť k rozsiahlemu a na chyby náchylnému kódu. AsyncLocalStorage ponúka elegantnejšie riešenie tým, že poskytuje spôsob ukladania a načítavania kontextových údajov v rámci jedného vykonávacieho kontextu, a to aj naprieč asynchrónnymi operáciami.

Predstavenie AsyncLocalStorage

AsyncLocalStorage je vstavaný modul Node.js (dostupný od verzie Node.js v14.5.0), ktorý poskytuje spôsob ukladania údajov, ktoré sú lokálne počas životnosti asynchrónnej operácie. V podstate vytvára úložný priestor, ktorý sa zachováva naprieč volaniami await, promises a inými asynchrónnymi hranicami. To umožňuje vývojárom pristupovať k kontextovým údajom a upravovať ich bez toho, aby ich museli explicitne odovzdávať.

Kľúčové vlastnosti AsyncLocalStorage:

• Automatická propagácia kontextu: Hodnoty uložené v AsyncLocalStorage sa automaticky šíria naprieč asynchrónnymi operáciami v rámci toho istého vykonávacieho kontextu.
• Zjednodušený kód: Znižuje potrebu explicitného odovzdávania kontextových objektov prostredníctvom volaní funkcií.
• Zlepšená pozorovateľnosť: Uľahčuje sledovanie požiadaviek a koreláciu záznamov a metrík.
• Bezpečnosť vlákien (Thread-Safety): Poskytuje bezpečný prístup ku kontextovým údajom v rámci aktuálneho vykonávacieho kontextu.

Prípady použitia AsyncLocalStorage

AsyncLocalStorage je cenný v rôznych scenároch, vrátane:

• Sledovanie požiadaviek: Priradenie jedinečného ID každej prichádzajúcej požiadavke a jeho propagácia počas celého životného cyklu požiadavky na účely sledovania.
• Autentifikácia a autorizácia: Ukladanie údajov o autentifikácii používateľa (napr. ID používateľa, roly, oprávnenia) na prístup k chráneným zdrojom.
• Zaznamenávanie a auditovanie: Pripojenie metaúdajov špecifických pre požiadavku k záznamom v logoch pre lepšie ladenie a auditovanie.
• Monitorovanie výkonu: Sledovanie času vykonávania rôznych komponentov v rámci požiadavky na analýzu výkonu.
• Správa transakcií: Správa transakčného stavu naprieč viacerými asynchrónnymi operáciami (napr. databázové transakcie).

Praktický príklad: Sledovanie požiadaviek s AsyncLocalStorage

Ukážme si, ako používať AsyncLocalStorage na sledovanie požiadaviek v jednoduchej aplikácii Node.js. Vytvoríme middleware, ktorý priradí jedinečné ID každej prichádzajúcej požiadavke a sprístupní ho počas celého životného cyklu požiadavky.

Príklad kódu

Najprv nainštalujte potrebné balíky (ak je to potrebné):

            npm install uuid express
            

              
                Copy
              
            
          

Tu je kód:

            // app.js
const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const { v4: uuidv4 } = require('uuid');

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();
const port = 3000;

// Middleware to assign a request ID and store it in AsyncLocalStorage
app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    next();
  });
});

// Simulate an asynchronous operation
async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      const requestId = asyncLocalStorage.getStore().get('requestId');
      console.log(`[Async] Request ID: ${requestId}`);
      resolve();
    }, 50);
  });
}

// Route handler
app.get('/', async (req, res) => {
  const requestId = asyncLocalStorage.getStore().get('requestId');
  console.log(`[Route] Request ID: ${requestId}`);
  await doSomethingAsync();
  res.send(`Hello World! Request ID: ${requestId}`);
});

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

V tomto príklade:

1. Vytvoríme inštanciu AsyncLocalStorage.
2. Definujeme middleware, ktorý priradí jedinečné ID každej prichádzajúcej požiadavke pomocou knižnice uuid.
3. Používame asyncLocalStorage.run() na vykonanie obsluhy požiadavky v kontexte AsyncLocalStorage. Tým sa zabezpečí, že akékoľvek hodnoty uložené v AsyncLocalStorage budú dostupné počas celého životného cyklu požiadavky.
4. Vnútri middleware uložíme ID požiadavky do AsyncLocalStorage pomocou asyncLocalStorage.getStore().set('requestId', requestId).
5. Definujeme asynchrónnu funkciu doSomethingAsync(), ktorá simuluje asynchrónnu operáciu a načíta ID požiadavky z AsyncLocalStorage.
6. V obsluhe cesty (route handler) načítame ID požiadavky z AsyncLocalStorage a zahrnieme ho do odpovede.

Keď spustíte túto aplikáciu a pošlete požiadavku na http://localhost:3000, uvidíte, že ID požiadavky sa zaznamená v obsluhe cesty aj v asynchrónnej funkcii, čo demonštruje, že kontext sa správne propaguje.

Vysvetlenie

• Inštancia AsyncLocalStorage: Vytvoríme inštanciu AsyncLocalStorage, ktorá bude uchovávať naše kontextové údaje.
• Middleware: Middleware zachytáva každú prichádzajúcu požiadavku. Generuje UUID a potom používa asyncLocalStorage.run na vykonanie zvyšku spracovania požiadavky *v rámci* kontextu tohto úložiska. Toto je kľúčové; zabezpečuje to, že všetko v ďalšom kroku má prístup k uloženým údajom.
• asyncLocalStorage.run(new Map(), ...): Táto metóda prijíma dva argumenty: novú, prázdnu mapu Map (môžete použiť aj iné dátové štruktúry, ak sú pre váš kontext vhodnejšie) a spätnú funkciu (callback). Spätná funkcia obsahuje kód, ktorý by sa mal vykonať v asynchrónnom kontexte. Akékoľvek asynchrónne operácie iniciované v rámci tejto spätnej funkcie automaticky zdedia údaje uložené v Map.
• asyncLocalStorage.getStore(): Toto vráti mapu Map, ktorá bola odovzdaná do asyncLocalStorage.run. Používame ju na ukladanie a načítavanie ID požiadavky. Ak run nebola zavolaná, vráti undefined, preto je dôležité volať run v rámci middleware.
• Asynchrónna funkcia: Funkcia doSomethingAsync simuluje asynchrónnu operáciu. Kľúčové je, že aj keď je asynchrónna (používa setTimeout), stále má prístup k ID požiadavky, pretože beží v kontexte vytvorenom pomocou asyncLocalStorage.run.

Pokročilé použitie: Kombinácia s knižnicami na logovanie

Integrácia AsyncLocalStorage s knižnicami na logovanie (ako Winston alebo Pino) môže výrazne zlepšiť pozorovateľnosť vašich aplikácií. Vkladaním kontextových údajov (napr. ID požiadavky, ID používateľa) do správ v logoch môžete ľahko korelovať záznamy a sledovať požiadavky naprieč rôznymi komponentmi.

Príklad s Winstonom

            // logger.js
const winston = require('winston');
const { AsyncLocalStorage } = require('async_hooks');

const asyncLocalStorage = new AsyncLocalStorage();

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.printf(({ timestamp, level, message }) => {
      const requestId = asyncLocalStorage.getStore() ? asyncLocalStorage.getStore().get('requestId') : 'N/A';
      return `${timestamp} [${level}] [${requestId}] ${message}`;
    })
  ),
  transports: [
    new winston.transports.Console()
  ]
});

module.exports = {
  logger,
  asyncLocalStorage
};

            

              
                Copy
              
            
          

            // app.js (modified)
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const { logger, asyncLocalStorage } = require('./logger');

const app = express();
const port = 3000;

app.use((req, res, next) => {
  const requestId = uuidv4();
  asyncLocalStorage.run(new Map(), () => {
    asyncLocalStorage.getStore().set('requestId', requestId);
    logger.info(`Incoming request: ${req.url}`); // Log the incoming request
    next();
  });
});

async function doSomethingAsync() {
  return new Promise(resolve => {
    setTimeout(() => {
      logger.info('Doing something async...');
      resolve();
    }, 50);
  });
}

app.get('/', async (req, res) => {
  logger.info('Handling request...');
  await doSomethingAsync();
  res.send('Hello World!');
});

app.listen(port, () => {
  logger.info(`App listening at http://localhost:${port}`);
});

            

              
                Copy
              
            
          

V tomto príklade:

• Vytvoríme inštanciu loggera Winston a nakonfigurujeme ju tak, aby do každej správy v logu zahrnula ID požiadavky z AsyncLocalStorage. Kľúčovou časťou je winston.format.printf, ktorá načíta ID požiadavky (ak je dostupné) z AsyncLocalStorage. Kontrolujeme, či asyncLocalStorage.getStore() existuje, aby sme sa vyhli chybám pri logovaní mimo kontextu požiadavky.
• Aktualizujeme middleware, aby zaznamenával URL prichádzajúcej požiadavky.
• Aktualizujeme obsluhu cesty a asynchrónnu funkciu, aby zaznamenávali správy pomocou nakonfigurovaného loggera.

Teraz budú všetky správy v logoch obsahovať ID požiadavky, čo uľahčí sledovanie požiadaviek a koreláciu záznamov.

Alternatívne prístupy: cls-hooked a Async Hooks

Predtým, ako sa stal AsyncLocalStorage dostupným, knižnice ako cls-hooked sa bežne používali na propagáciu asynchrónneho kontextu. cls-hooked používa Async Hooks (nižšiu úroveň Node.js API) na dosiahnutie podobnej funkcionality. Hoci sa cls-hooked stále často používa, AsyncLocalStorage je všeobecne preferovaný kvôli svojej vstavanej povahe a lepšiemu výkonu.

Async Hooks (async_hooks)

Async Hooks poskytujú API na nižšej úrovni na sledovanie životného cyklu asynchrónnych operácií. Hoci je AsyncLocalStorage postavený na Async Hooks, priame používanie Async Hooks je často zložitejšie a menej výkonné. Async Hooks sú vhodnejšie pre veľmi špecifické, pokročilé prípady použitia, kde je potrebná jemnozrnná kontrola nad asynchrónnym životným cyklom. Vyhnite sa priamemu používaniu Async Hooks, pokiaľ to nie je absolútne nevyhnutné.

Prečo uprednostniť AsyncLocalStorage pred cls-hooked?

• Vstavaný: AsyncLocalStorage je súčasťou jadra Node.js, čo eliminuje potrebu externých závislostí.
• Výkon: AsyncLocalStorage je vo všeobecnosti výkonnejší ako cls-hooked vďaka svojej optimalizovanej implementácii.
• Údržba: Ako vstavaný modul je AsyncLocalStorage aktívne udržiavaný tímom jadra Node.js.

Úvahy a obmedzenia

Hoci je AsyncLocalStorage silný nástroj, je dôležité si byť vedomý jeho obmedzení:

• Hranice kontextu: AsyncLocalStorage propaguje kontext iba v rámci toho istého vykonávacieho kontextu. Ak prenášate údaje medzi rôznymi procesmi alebo servermi (napr. prostredníctvom front správ alebo gRPC), stále budete musieť explicitne serializovať a deserializovať kontextové údaje.
• Úniky pamäte: Nesprávne použitie AsyncLocalStorage môže potenciálne viesť k únikom pamäte, ak sa kontextové údaje riadne neuvoľnia. Uistite sa, že používate asyncLocalStorage.run() správne a vyhýbajte sa ukladaniu veľkého množstva údajov do AsyncLocalStorage.
• Zložitosť: Hoci AsyncLocalStorage zjednodušuje propagáciu kontextu, môže tiež pridať zložitosť do vášho kódu, ak sa nepoužíva opatrne. Uistite sa, že váš tím rozumie, ako funguje, a dodržiava osvedčené postupy.
• Nie je náhradou za globálne premenné: AsyncLocalStorage *nie je* náhradou za globálne premenné. Je špeciálne navrhnutý na propagáciu kontextu v rámci jednej požiadavky alebo transakcie. Jeho nadmerné používanie môže viesť k pevne viazanému kódu a sťažiť testovanie.

Osvedčené postupy pre používanie AsyncLocalStorage

Pre efektívne používanie AsyncLocalStorage zvážte nasledujúce osvedčené postupy:

• Používajte middleware: Použite middleware na inicializáciu AsyncLocalStorage a uloženie kontextových údajov na začiatku každej požiadavky.
• Ukladajte minimálne údaje: Ukladajte iba nevyhnutné kontextové údaje do AsyncLocalStorage, aby ste minimalizovali zaťaženie pamäte. Vyhnite sa ukladaniu veľkých objektov alebo citlivých informácií.
• Vyhnite sa priamemu prístupu: Zapuzdrite prístup k AsyncLocalStorage za dobre definované API, aby ste sa vyhli pevnému viazaniu a zlepšili udržiavateľnosť kódu. Vytvorte pomocné funkcie alebo triedy na správu kontextových údajov.
• Zvážte spracovanie chýb: Implementujte spracovanie chýb, aby ste elegantne zvládli prípady, keď AsyncLocalStorage nie je správne inicializovaný.
• Dôkladne testujte: Píšte jednotkové a integračné testy, aby ste sa uistili, že propagácia kontextu funguje podľa očakávania.
• Dokumentujte použitie: Jasne zdokumentujte, ako sa AsyncLocalStorage používa vo vašej aplikácii, aby ostatní vývojári pochopili mechanizmus propagácie kontextu.

Integrácia s OpenTelemetry

OpenTelemetry je open-source framework pre pozorovateľnosť, ktorý poskytuje API, SDK a nástroje na zber a export telemetrických údajov (napr. stopy, metriky, logy). AsyncLocalStorage je možné bezproblémovo integrovať s OpenTelemetry na automatickú propagáciu kontextu stôp naprieč asynchrónnymi operáciami.

OpenTelemetry sa vo veľkej miere spolieha na propagáciu kontextu na koreláciu stôp naprieč rôznymi službami. Použitím AsyncLocalStorage môžete zabezpečiť, že kontext stopy sa správne propaguje v rámci vašej aplikácie Node.js, čo vám umožní vybudovať komplexný systém distribuovaného sledovania.

Mnohé SDK OpenTelemetry automaticky využívajú AsyncLocalStorage (alebo cls-hooked, ak AsyncLocalStorage nie je k dispozícii) na propagáciu kontextu. Konkrétne podrobnosti nájdete v dokumentácii vami zvoleného SDK OpenTelemetry.

Záver

AsyncLocalStorage je cenný nástroj na správu propagácie asynchrónneho kontextu v serverových JavaScript aplikáciách. Jeho použitím na sledovanie požiadaviek, autentifikáciu, logovanie a iné prípady použitia môžete vytvárať robustnejšie, pozorovateľnejšie a udržiavateľnejšie aplikácie. Hoci existujú alternatívy ako cls-hooked a Async Hooks, AsyncLocalStorage je vo všeobecnosti preferovanou voľbou vďaka svojej vstavanej povahe, výkonu a jednoduchosti použitia. Nezabudnite dodržiavať osvedčené postupy a byť si vedomí jeho obmedzení, aby ste efektívne využili jeho možnosti. Schopnosť sledovať požiadavky a korelovať udalosti naprieč asynchrónnymi operáciami je kľúčová pre budovanie škálovateľných a spoľahlivých systémov, najmä v architektúrach mikroslužieb a zložitých distribuovaných prostrediach. Použitie AsyncLocalStorage pomáha dosiahnuť tento cieľ, čo v konečnom dôsledku vedie k lepšiemu ladeniu, monitorovaniu výkonu a celkovému zdraviu aplikácie.